Creating and Configuring a Custom Visualization Component

1. In the Studio header, click the Configuration Options icon and select Control Panel. :

   

2. From the Control Panel select Custom Visualizations.

   

3. Click + Component:

   
4. Specify a name for the component. This is the display name of the component in the Discover menu.
5. Optionally, check Browse to locate an icon image for the component and then click Upload and Ok.
6. In JavaScript File, specify the JavaScript file that implements your Custom Visualization Component by clicking Browse, locating the file, and clicking Open.
7. In Renderer class, specify the fully qualified name of the JavaScript class that renders the component.
   For example, in the following JavaScript snippet, the name of the renderer class is Oracle.BDD.Portlets.Visualization.Renderers.DonutPieChart:
      
   

   Oracle.BDD.Portlets.Visualization.Renderers.DonutPieChart =
   Oracle.BDD.Portlets.Visualization.Renderers.BaseRenderer.extend({
   init: function() {
     /**
     * Get the queryConfig for the initial query
     */
     var queryConfig = this.getQueryConfig("eql");
     …
   });

   This rendering class uses the CVC JavaScript API to initiate queries and render the returned data to the portlet.  Please refer to the Developing a Renderer Class section of this document for more details on how to write this code.
8. Select a Sort type of one of the following:
   •    None - Specifies that there is no sort option available for the business user to configure in the component.
   •    Defined - Specifies that the sort option for the component is defined by token replacement in an EQL statement. A business user then sorts by value of the token in either an ascending or descending order.  Please refer to the Visualization Configuration section of this document for details on the token definitions and usage.
   •    Per Dimension - Specifies that a sort option is available for any token defined as a dimension. Please refer to the Visualization Configuration section of this document for details on the token definitions and usage.
9. Optionally, expand Advanced Options and specify the following:
   •    CSS - Specifies visualization-specific CSS. Also note that the CSS is scoped to the visualization's DOM container.
   •    External CSS - Specifies a list of URLs to external CSS files. Each URL should be line separated. These CSS files override any CSS in the JavaScript file.  This last line is inaccurate.  There is no CSS in the JavaScript file.  
   •    External JavaScript - Specifies a list of URLs to external JavaScript files. Each URL should be line separated. These JavaScript files might provide additional resources, such as third-party plugins, to support the JavaScript file.  Could we call it the “JavaScript renderer” rather than “file”?                    

 

10. Click Next.
11. In EQL query name, specify the name of the EQL query used in the JavaScript API function getQueryConfig.

var
queryConfig = this.getQueryConfig("eql");
...

12. Paste the EQL query for your component into the text box.  For details of EQL syntax please refer to the Oracle Big Data Discovery EQL Reference Guide.

 

13. Click Detect Tokens

14. If any of the tokens are incorrectly categorized, click the token and drag and drop it into the correct category.  For the case of the Donut_Pie custom component you need to drag and drop num_recs into the DATA category.
    
15.   Click each token name and specify the details of how the token is used in the component.

16. Optionally, you can add more EQL queries to the component by clicking + and repeating steps 11 – 15 for each EQL query. Each query that you add generates an additional result set for the component to use.

17. Click Save.

18. From the custom visualizations menu in Studio’s Control Panel check Published to publish this component.  This allows this custom visualization to be used by non-administration type users.

As the developer of the custom visualization component you may want to keep this CVC unpublished until you test using it in a Discover project.

For more details on publishing, unpublishing and deleting custom visualization components please refer to the respective sections covered later in this tutorial.

1. From Studio’s Catalog, find the project in which you want to use the CVC and click it to open the project

   

2. Click Discover.

   
3. From the Add Component menu find the Custom Visualization Component (located toward the bottom of the list) and drag it on to the page.

4. In the Custom Visualization Component, click the pencil icon to edit the configuration settings.

5. In the Visualization Setting section, select the appropriate attributes for each token defined in the CVC definition.  For the Donut_Pie CVC example using a sample workforce_hr data set  (sample data set is not provided with this distribution) the 3 attributes specified are:
   metric_1 = hr_termination_count  (aggregation type = sum)
   groupby_1 = hr_source_event_reason_description
   groupby_2 =  hr_employee_high_potential_flag

   

Notice the visualization now is displayed.  You can click and/or mouse over various sections of the donut to report more information.

For example, using this particular data set if you click on Better Opportunity part of the donut, you see additional information displayed within the donut (in this case, if the employee who resigned was tagged by HR as a high potential employee).

Sample Query

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_1% AS groupby
FROM "%dataview%"
GROUP BY groupby
ORDER BY metric %sort%
PAGE(0,%num_recs%);

Prior to query execution, the EQL is parsed for tokens and a string value is substituted according to the "type" of token used:

 
Token configuration settings to use in Studio’s Control Panel when creating the CVC

1. On page load, the CVC client-side controller inspects the visualization configuration and renders a dropdown control for each attribute, view and sort token in the 'Edit Settings' panel. Default values are set according to the user's saved default state.
2. The CVC controller instantiates an instance of the renderer class and calls its init() function
3.  In the init() function, a queryConfig object for the EQL query to execute is acquired. The queryConfig references an EQL statement and contains the token values set by user selection.
4. Token values may also be set by accessing the token from the queryConfig object and modifying its properties
5. The renderer class executes the query, passing the queryConfig and specifying a function to call when the results have returned
6. The CVC controller executes an Ajax call to the portlet backend to query for the data
7. The query results are bundled in a queryResults object which is passed to the callback function
8. A reference to the renderer's allocated DOM space, called the canvas, is acquired and the visualization is drawn by appending HTML and SVG elements to the canvas's top-level, or _root_, element

 Oracle.BDD.Portlets.Visualization.Renderers.DonutPieChart = 
Oracle.BDD.Portlets.Visualization.Renderers.BaseRenderer.extend({

init: function() {
  /**
   * Get the queryConfig for the initial query
   */
  var queryConfig = this.getQueryConfig("eql");
  /**
   * Set default value for num_recs data token
   */
  queryConfig.getToken("num_recs").setValue("10");

  /**
   * Execute the initial query, indicating renderDonut()
   * as the callback  
  /*
  this.executeQuery(queryConfig, true, this.renderDonut);
  },

  /**
   * Callback function to render donut
   */
  renderDonut: function(queryResults) {
   /**
    * Acquire reference to canvas
    */
    */
  var canvas = this.getCanvas();

  /**
   * Acquire reference to canvas root
   */
   */
  var root = canvas.getRoot();
  }
});

/**
* Get the queryConfig for the initial query
*/
var queryConfig = this.getQueryConfig("eql");

/**
* Get the queryConfig for the initial query
*

var queryConfig = this.getQueryConfig("eql");

/**
* Set default value for num_recs data token
*/
if (!queryConfig.getToken("num_recs").getValue()){
queryConfig.getToken("num_recs").setValue("10");
}

/**
* Execute the initial query, indicating renderDonut()
* as the callback
*/
this.executeQuery(queryConfig, true, this.renderDonut);

var queryConfig = this.getQueryConfig("drilldown");
this.executeQuery(queryConfig, false, this.renderPieChart, [datum, innerRadius]);

...

/**
* Renders the pie chart
*/
renderPieChart: function(queryResults, datum, radius) {

// Render pie chart
}

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_1% AS groupby
FROM "%dataview%"
GROUP BY groupby;

The Color Manager may be used to manage color. The Color Manager the D3 Ordinal Scales, the is standard practice for visualization color management when working with D3. Using an ordinal scale provides consistency of color when it is desired to associate a color with a specific data point. For example, a grouped bar chart that renders multiple bars, with each bar representing a different metric, for each group by value. It is desired that when a bar representing a metric is rendered that it is colored the same as every other bar representing that metric. The Color Manager provides this capability.

The following example represents the most basic use of the Color Manager. When getColor("border") is first called on the Color Manager, the next unassigned color in the Color Manager's color library is returned. Subsequent calls to getColor("border") return the same color value.

var colorMgr = this.getColorManager();
 var borderColor = colorMgr.getColor("border");

 ...

// Use the same color for the divider as was used for the border
var dividerColor = colorMgr.getColor("border");

var colorMgr = this.getColorManager({
  library: ["#cccccc", "#999999", "#666666"]
});

var colorMgr = new Oracle.BDD.Portlets.Visualization.Util.ColorManager({
  library: ["#cccccc", "#999999", "#666666"]
});

var colorMgr = this.getColorManager();
colorMgr.setLibrary(["#cccccc", "#999999", "#666666"]);

var colorMgr = this.getColorManager({
 scaleDomain: ["High", "Mid", "Low"]
});

var colorMgr = new Oracle.BDD.Portlets.Visualization.Util.ColorManager({
  scaleDomain: ["High", "Mid", "Low"]
});

var colorMgr = this.getColorManager();
colorMgr.setScaleDomain(["High", "Mid", "Low"]);

Any element on the canvas may be equipped with a mouseover tooltip by adding the bdd:tooltip attribute to the element's tag.

Tooltips

labels.attr("bdd:tooltip", "Click to refine")
  .text(function(d) { return d.data.groupby; })

The JavaScript API allows for simple refinement of the navigation state. When refinements are added to the QueryConfig object and the query is executed, all portlets on the page that respond to data change events will be effected.

In this example, labels are given an onclick event listener which responds by adding a refinement to the groupby_1 token's attribute, setting the groupby property value as its refinement value. The query is then executed, designating self.renderPieChart as the callback function.

Add Refinement

labels.on('click', function(d,i) {
  queryConfig.addRefinement('groupby_1', d.groupby);
  self.executeQuery(queryConfig, true, self.renderPieChart);
});

labels.on('click', function(d,i) {
  self.refine(queryConfig, 'groupby_1', d.groupby, self.renderPieChart);
});

When an error is received from portlet is response to a query, the default behavior is to clear the canvas of any content and display the error in the portlet (not in the visualization or in the canvas space).

showPieChart: function(segment, d, innerRadius) {

  this.clearPieChart();

  var queryConfig = this.getQueryConfig("drilldown");
  queryConfig.getToken("filter").setValue(d.data.groupby);

  this.executeQuery(queryConfig, false, this.renderPieChart, [d, innerRadius], this.handleQueryError);
},

handleQueryError: function(err) {

  d3.select(this.getCanvas().getRoot())
    .select(".wrapper")
    .append("text")
    .attr("width", 200)
    .attr("text-anchor", "middle")
    .attr("text-align", "center")
    .attr("fill", "red")
    .attr("class", "error")
    .text(err);
}

Portlet Messaging

displayMessage(msg, clear) displays the provided message in the portlet "info" messaging space.

Clearing Canvas Content When Displaying Messaging

In both displayError(err, clear) and displayMessage(msg, clear), the clear parameter may be passed to indicate if the canvas should be cleared of content when the message displays.

/**
 * Contents of the canvas root are cleared and an error message is displayed in the portlet space.
 */
this.displayError("Visualization could not be rendered", true);

/**
 * Error message is displayed in the portlet space while keeping canvas content intact.
 */
this.displayError("Refresh page.", false);

Zero Results

Valid queries that return 0 records do not invoke error callback functions. The renderer class is expected to implement handling for 0 results conditions in the query callback function according to the needs of the visualization.

Zero Results

if (queryResults.getRecordCount() == 0) {
  this.displayMessage("Query returned no results", true);
}

Number of Results > Number of Returned Records

Certain visualizations require that all records from a query are returned for the visualization to render accurately. Call queryResults.getRecordCount() and queryResults.getTotalRecordCount() to evaluate for this condition.

Results Exceed Returned

if (queryResults.getRecordCount() != queryResults.getTotalRecordCount()) {
  this.displayError("This visualization requires more records than can be returned in one query.", true);
}

In the examples above, the Visualization Configuration is:

Visualization name  =   Donut_Pie (CVC can be user defined during configuration in Studio)

JavaScript file  =   donut_pie_renderer.js  This file is available in the CVC_sample_code.zip file. It can be found and downloaded from the Before You Begin -> What Do You Need? section of this tutorial.

Renderer class =    Oracle.BDD.Portlets.Visualization.Renderers.DonutPieChart

Sort type =    Defined

Advanced Options
CSS    

.label, .path {
cursor: pointer;
}

EQL Queries
eql =

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_1% AS groupby
FROM "%dataview%"
GROUP BY groupby
ORDER BY metric %sort%
PAGE(0,%num_recs%);

drilldown  =  

RETURN data AS SELECT
%metric_1% AS metric,
%groupby_2% AS groupby
FROM "%dataview%"
WHERE %groupby_1% = '%filter%'
GROUP BY groupby
ORDER BY metric %sort%
PAGE(0,%num_recs%);

Tokens